Referência da API

BtgPayClient

class BtgPayClient(context: Context)

Métodos

Método	Assinatura	Descrição
connect	fun connect(listener: ConnectionListener)	Conecta ao serviço BTG Pay
disconnect	fun disconnect()	Desconecta do serviço, cancelando operações em andamento
isCommissioned	fun isCommissioned(): Boolean	Retorna se o terminal está comissionado
startCommissioning	fun startCommissioning(cnpj: String, activationCode: String, listener: CommissioningListener)	Inicia o comissionamento do terminal
cancelWorkflow	fun cancelWorkflow()	Cancela o fluxo em andamento sem desconectar do serviço. Também chamado internamente por disconnect()

Propriedades

Propriedade	Tipo	Descrição
isConnected	Boolean	true quando conectado ao serviço
sdkVersion	String?	Versão do SDK
sdkBuildId	String?	Identificador do build
printer	PrinterApi	Subsistema de impressão

ConnectionListener

interface ConnectionListener {
    fun onConnected()
    fun onDisconnected()
    fun onBindFailed()
    fun onInitFailed(reason: String)
}

Callback	Quando é chamado
onConnected	Conexão estabelecida com o serviço
onDisconnected	O processo do serviço morreu; o Android tentará reconectar automaticamente
onBindFailed	O serviço não está instalado no terminal
onInitFailed	Falha na inicialização do serviço; o binding é desfeito automaticamente

Comportamento de connect:

• Se o client já está conectado, onConnected é invocado imediatamente.
• Se já está em processo de conexão, o novo listener substitui o anterior e a conexão em andamento é reaproveitada.
• Após onDisconnected, o Android mantém o binding ativo — onConnected será chamado novamente quando o serviço voltar.

CommissioningListener

interface CommissioningListener {
    fun onSuccess()
    fun onError(message: String)
}

Callback	Quando é chamado
onSuccess	Comissionamento concluído
onError	Falha no comissionamento; message descreve o motivo

Os callbacks são invocados na Binder thread. Operações de UI devem ser despachadas para a main thread.

PrinterApi

interface PrinterApi {
    suspend fun print(build: PrintJobScope.() -> Unit): Result<Unit>
    suspend fun print(job: PrintJob): Result<Unit>
    suspend fun setReceiptTemplate(svg: String): Result<Unit>
    fun clearReceiptTemplate()
    suspend fun status(): PrinterStatus
}

Método	Descrição
print(build)	Constrói e imprime um job em uma chamada
print(job)	Imprime um PrintJob construído previamente
setReceiptTemplate(svg)	Instala um template SVG de comprovante (validado imediatamente)
clearReceiptTemplate()	Remove o template customizado, revertendo ao modelo do BTG
status()	Consulta o estado da impressora

Funções top-level

printJob

fun printJob(build: PrintJobScope.() -> Unit): PrintJob

Constrói um PrintJob imutável e reutilizável. Útil para imprimir o mesmo conteúdo mais de uma vez (ex.: segunda via). Ver Reutilizar um job.

PrintJobScope

fun text(
    text: String,
    size: Int = 16,
    align: Align = Align.LEFT,
    bold: Boolean = false,
    marginLeft: Int = 0,
    marginRight: Int = 0,
    lineSpace: Int = 0,
)

fun image(
    png: ByteArray,
    align: Align = Align.CENTER,
    marginLeft: Int = 0,
    marginRight: Int = 0,
)

fun qr(content: String, align: Align = Align.CENTER, size: Int = 240)

fun feed(lines: Int = 1)

Tipos

Align

enum class Align { LEFT, CENTER, RIGHT }

PrinterStatus

sealed interface PrinterStatus {
    data object Ready : PrinterStatus
    data object NoPaper : PrinterStatus
    data object Overheated : PrinterStatus
    data object Unavailable : PrinterStatus
}

PrintJob

data class PrintJob(val elements: List<PrintElement>)

PrintElement

sealed interface PrintElement {
    data class Text(
        val text: String,
        val size: Int,
        val align: Align,
        val bold: Boolean,
        val marginLeft: Int,
        val marginRight: Int,
        val lineSpace: Int,
    ) : PrintElement

    data class Image(
        val png: ByteArray,
        val align: Align,
        val marginLeft: Int,
        val marginRight: Int,
    ) : PrintElement

    data class Qr(val content: String, val align: Align, val size: Int) : PrintElement

    data class Feed(val lines: Int) : PrintElement
}

PrintException

class PrintException(
    val brn: String,
    val severity: String,
    override val message: String,
    val details: String? = null,
    val failedElementIndex: Int? = null,
) : Exception(message)

Códigos de erro — Impressão

Hardware e estado

brn	Significado
brn:btg:pay:hal:printer:out-of-paper	Sem papel
brn:btg:pay:hal:printer:overheating	Cabeça superaquecida
brn:btg:pay:hal:printer:hardware-failure	Falha de hardware
brn:btg:pay:hal:printer:printer-timeout	A impressora não respondeu

Job recusado

brn	Significado
brn:btg:pay:hal:printer:empty-job	Nenhum elemento no job
brn:btg:pay:hal:printer:too-many-elements	Acima de 32 elementos
brn:btg:pay:hal:printer:image-too-large	Imagem acima de 512 KB
brn:btg:pay:hal:printer:text-too-long	Texto acima de 4.096 caracteres
brn:btg:pay:hal:printer:payload-too-large	Job somando mais de 768 KB
brn:btg:pay:hal:printer:qr-render-failed	Conteúdo longo demais ou size pequeno demais
brn:btg:pay:hal:printer:malformed-job	Job inválido na travessia AIDL

Concorrência e disponibilidade

brn	Significado
brn:btg:pay:hal:printer:printer-busy	Outro job em andamento
brn:btg:pay:hal:printer:printer-unavailable	Sem impressora no terminal
brn:btg:pay:hal:printer:job-timed-out	O job passou do tempo máximo
brn:btg:pay:hal:printer:timeout	O serviço não respondeu
brn:btg:pay:hal:printer:transport-failure	Falha na chamada ao serviço

Campos do template de comprovante

Campo	Conteúdo	Exemplo
{{merchant_name}}	Nome do estabelecimento	MERCADO SILVA
{{cnpj}}	CNPJ formatado	30.306.294/0001-45
{{date}}	Data da transação	29/09/2026
{{time}}	Hora da transação	19:30
{{via_label}}	Qual via	VIA DO CLIENTE
{{payment_method}}	Meio de pagamento	CREDITO
{{amount}}	Valor total	R$ 50,00
{{installments_label}}	Rótulo de parcelamento	3X SEM JUROS DE
{{installment_amount}}	Valor da parcela	R$ 16,67
{{qr_url}}	URL do QR como texto	https://nf.e/abc
{{qr}}	QR desenhado na origem	Posicionar com <g transform>

Erros de validação do template

Erro	Causa
template is N bytes, over the 262144 byte limit	Template acima de 256 KB
external reference is not allowed, only data: URIs: X	href para arquivo ou URL
unknown placeholder: {{X}}	Nome fora da tabela de campos
unterminated placeholder: missing }}	Faltou fechar }}
unterminated attribute value	Atributo com aspas não fechadas
template does not rasterize: X	SVG inválido

Limites

Limite	Valor
Largura do papel	384 px
Elementos por job	32
Caracteres por texto	4.096
Bytes por imagem	512 KB
Bytes por job (soma)	768 KB
Bytes do template	256 KB (262.144)
Timeout de print	90 s
Timeout de setReceiptTemplate	15 s
Timeout de status	5 s